Places Around
=============

This is a Nokia Developer Qt Quick example application, ported from iPhone,
demonstrating the use of Social Connect QML Plug-in for user authentication and
retrieving the nearby places from Facebook. The example also features Qt
Mobility Location API; the places found are placed on Nokia Maps which is
centered based on the user's current location. In addition, route drawing
feature plots the route from the current location to the selected point of
interest.

This example application is hosted in Nokia Developer Projects:
- http://projects.developer.nokia.com/placesaround

For more information on implementation and porting, visit the wiki pages:
- http://projects.developer.nokia.com/placesaround/wiki
- http://projects.developer.nokia.com/placesaround/wiki/porting


1. Usage
-------------------------------------------------------------------------------

The use of the application requires a Facebook account. When starting the
application for the first time, or if the access token is expired, you must
login to Facebook using your username and password. The login page is
automatically shown when a new access token is required.


2. Project structure and implementation
-------------------------------------------------------------------------------

2.1 Folders
-----------

 |                  The root folder contains the project file, resource files,
 |                  the license information and this file (release notes).
 |
 |- bin             Contains the installable binaries.
 |
 |- gfx             Contains application graphics.
 |
 |- icons           Contains application icons.
 |
 |- qml             Root folder for QML and JavaScript files.
 |  |
 |  |- common       Common, cross-platform QML and JavaScript files.
 |  |
 |  |- harmattan    Harmattan specific QML and JavaScript files.
 |  |
 |  |- symbian      Symbian specific QML and JavaScript files.
 |
 |- qtc_packaging   Contains the Harmattan (Debian) packaging files.
 |
 |- rsc             Contains the Qt resource system files.
 |
 |- socialconnect   The root folder of the Social Connect QML Plug-in.
 |
 |- src             Contains the Qt/C++ source code files.

 
2.2 Important files and classes
-------------------------------

| File                           | Description                                |
|--------------------------------|--------------------------------------------|
| src/networkaccess.h            | Provides the implementation for adding a   |
|                                | custom user agent. Needed to make sure     |
|                                | that the login page is shown correctly.    |
|--------------------------------|--------------------------------------------|
| src/placeslistmodel.h/cpp      | A model for the landmarks constructed      |
|                                | based on the data retrieved from Facebook. |
|--------------------------------|--------------------------------------------|
| src/routemanager.h/cpp         | RouteManager class is responsible for      |
|                                | creating the route on the map. The route   |
|                                | drawn in the QML code.                     |
|--------------------------------|--------------------------------------------|
| src/settings.h/cpp             | Contains the implementation of storing and |
|                                | restoring application specific settings.   |
|--------------------------------|--------------------------------------------|
| qml/.../LoginPage.qml          | The login page encapsulating LoginView     |
|                                | element implemented by the plug-in.        |
|--------------------------------|--------------------------------------------|
| qml/.../PlacesDetailPage.qml   | The page for showing the details of a      |
|                                | selected point of interest.                |
|--------------------------------|--------------------------------------------|
| qml/.../PlacesListPage.qml     | The page showing the places in a list view.|
|--------------------------------|--------------------------------------------|
| qml/.../PlacesMapPage.qml      | The page showing the places on a map.      |
|--------------------------------|--------------------------------------------|
| qml/common/PlacesMap.qml       | An element containing the map and all the  |
|                                | items placed on it.                        |
|--------------------------------|--------------------------------------------|


2.3 Important APIs and QML elements used
----------------------------------------

Qt Mobility Location API (Qt C++):
- QGeoCoordinate
- QGeoRouteReply
- QGeoRoutingManager
- QGeoServiceProvider
- QLandmarkManager

Qt Mobility Location API (QML):
- LandmarkProximityFilter
- Map
- MapCircle
- MapImage
- MapObjectView
- PositionSource


3. Compatibility
-------------------------------------------------------------------------------

 - Symbian devices with Qt 4.7.4, Qt Mobility 1.2.1 and Qt Quick Components 1.1.
 - Nokia N9 (MeeGo 1.2 Harmattan).

Developed with Qt SDK 1.2.

3.1 Required Capabilities
-------------------------

None; The application can be self signed on Symbian.

3.2 Known Issues
----------------

- In Harmattan the landmarks are not updated properly on the map or they are
  updated inconsistently.
- Performance is poor when panning the map while landmarks are drawn on the
  screen.
- A wrong button is sometimes checked in the tool bar due to a bug. See
  http://bugreports.qt-project.org/browse/QTCOMPONENTS-1178


4. Building, installing, and running the application
-------------------------------------------------------------------------------

4.1 Preparations
----------------

Check that you have the latest Qt SDK installed in the development environment
and the latest Qt version on the device.

4.2 Using the Qt SDK
--------------------

You can install and run the application on the device by using the Qt SDK.
Open the project in the SDK, set up the correct target (depending on the device
platform), and click the Run button. For more details about this approach,
visit the Qt Getting Started section at Nokia Developer
(http://www.developer.nokia.com/Develop/Qt/Getting_started/).

4.3 Symbian device
------------------

Make sure your device is connected to your computer. Locate the .sis
installation file and open it with Ovi Suite. Accept all requests from Ovi
Suite and the device. Note that you can also install the application by copying
the installation file onto your device and opening it with the Symbian File
Manager application.

After the application is installed, locate the application icon from the
application menu and launch the application by tapping the icon.

4.4 Nokia N9 and Nokia N950
---------------------------

Copy the application Debian package onto the device. Locate the file with the
device and run it; this will install the application. Note that you can also
use the terminal application and install the application by typing the command
'dpkg -i <package name>.deb' on the command line. To install the application
using the terminal application, make sure you have the right privileges 
to do so (e.g. root access).

Once the application is installed, locate the application icon from the
application menu and launch the application by tapping the icon.


5. License
-------------------------------------------------------------------------------

See the license text file delivered with this project. The license file is also
available online at
http://projects.developer.nokia.com/placesaround/browser/trunk/licence.txt


6. Related documentation
-------------------------------------------------------------------------------
Qt Quick Components
- http://doc.qt.nokia.com/qt-components-symbian-1.1/index.html
- http://harmattan-dev.nokia.com/docs/library/html/qt-components/qt-components.html

Qt Mobility Location API:
- http://doc.qt.nokia.com/qtmobility/location-overview.html

Tutorial for Facebook developers:
- http://developers.facebook.com/docs/appsonfacebook/tutorial/


7. Version history
-------------------------------------------------------------------------------

1.0 Initial release
